#lang scribble/base

@(require "shared.rkt" scribble/core)

@title[#:tag "branch-and-commit"]{@;{Retiquette: Branch and Commit}重新排序：分支与提交}

 @;{This section is specifically for Racketeers who commit to the Racket code
 base.}
本节专门针对那些使用Racket代码库的Racket成员。

 @;{Working with the bug database requires one critical work flow rule.}
使用bug数据库需要一个关键的工作流规则。

 @;{Working with the code base requires style rules for actions on the
 repository. Currently we are using Git and below are a few rules on how to
 act in this context.}
使用代码库需要存储库上操作的样式规则。目前我们正在使用Git，下面是一些关于如何在这种情况下操作的规则。

@;-----------------------------------------------------------------------------
@section{@;{Bugfix Workflow}错误修复工作流}

@;{Re-assign bug reports only after you can eliminate your own code as the source
 of a bug. The best way to accomplish this goal is to create a new example that
 re-creates the problem without involvement of your code. When you have such a
 code snippet, re-assign the code to the person responsible for the apparently
 buggy component and submit the code snippet as part of the justification.}
只有在可以消除自己的代码作为错误源之后，才能重新分配错误报告。实现这一目标的最佳方法是创建一个新的示例，该示例在不涉及代码的情况下重新创建问题。当你有这样的代码片段时，请将代码重新分配给负责明显有问题的组件的人员，并将代码片段作为理由的一部分提交。

@; -----------------------------------------------------------------------------
@section{@;{Commit}提交}

@;{@bold{New feature commit:} Commit the new feature, its tests, and its
 documentations as you wish, but please push them together. However, do not
 commit states that don't run. (In Git, this means 'commit' and not just
 'push'.)}
@bold{新特性提交：}按照你的意愿提交新特性、它的测试和它的文档，但是请将它们推到一起。但是，不要提交不运行的状态。（在Git中，这意味着“提交”，而不仅仅是“推送”。）

@;{@bold{Bug fix commit:} When you fix a bug, make sure to commit (1) the
 code delta, (2) the new test case, and (3) the revised docs (if
 applicable) in one batch. If the creation of a single commit is too
 complex of if you wish to factor out one of the commits, please push all
 pieces at once. That way the code base is always in a state where code,
 tests, and documentation are in sync, and readers of commit messages can
 evaluate changes completely.}
Bug fix @bold{错误修复提交：}修复Bug时，确保（1）代码增量，（2）新的测试用例，以及（3）修改后的文档（如果适用）一批提交。如果一个提交的创建过于复杂，如果你希望排除其中一个提交，请立即推送所有部分。这样，代码库始终处于代码、测试和文档同步的状态，提交消息的读取器可以完全评估更改。

@;{@bold{Style change commit:} Submit changes to the style of a file
 separately from changes to its behavior (new features, bugs).}
@bold{样式更改提交：}将对文件样式的更改与对其行为（新功能、错误）的更改分开提交。

@;{Write meaningful commit messages. The first line (say 72 chars) should
 provide a concise summary of the commit. If the message must be longer,
 edit the rest of the message in your text editor and leave a blank line
 between the summary line and the rest of the message, like this:}
编写有意义的提交消息。第一行（比如72个字符）应该提供提交的简明摘要。如果邮件必须较长，请在文本编辑器中编辑邮件的其余部分，并在摘要行和邮件的其余部分之间留一个空行，如下所示：

@verbatim[#:indent 2]{
 some quick description（一些简短的描述）

 more blah blah blah, with more（更多，更多）
 details about the actual change（实际变动明细）
}
 @;{The advantage of a blank line is that @tt{git log} and other tools display
 the commit messages properly. If you prefer the @tt{-m} command line flag
 over an editor, you can use several of them in a row.}
空行的优点是@tt{git日志}和其他工具可以正确显示提交消息。如果你更喜欢@tt{-m}命令行标志而不是编辑器，则可以一行使用其中的几个标志。

@;{The message for bug report fixes should contain ``Close PR NNNNN'' so that
 bug reports are automatically closed.}
错误报告修复的消息应包含“Close PR NNNNN”，以便错误报告自动关闭。

@;{To avoid `merge commits', update your repository with
@element['tt @list{git --rebase pull}].}
为了避免“合并提交”，请使用@element['tt @list{git --rebase pull}]更新存储库。

@; -----------------------------------------------------------------------------
@section{@;{No Commit ``Bombs,'' Please}请不要提交“炸弹”}

@;{On occasion, you will find that you are spending a significant amount of
 time working with someone else's code. To avoid potentially painful
 merges, please (1) inform the author when you create the branch and (2)
 set the mail hook so that git sends a commit message to both you and the
 original author. Furthermore, you should test your changes on the actual
 code base. In some cases it is acceptable to delay such tests, e.g., when
 you will not know for a long time whether the performance implications
 allow a commit to the PLT repository.}
有时，你会发现你花了大量时间处理别人的代码。为了避免潜在的不愉快的合并，请（1）在创建分支时通知作者，（2）设置邮件挂钩，以便git向你和原作者发送提交消息。此外，你应该在实际的代码基础上测试你的更改。在某些情况下，延迟这样的测试是可以接受的，例如，当你很长时间不知道性能影响是否允许提交到PLT存储库时。
